fix: verify WWPGD commit pins at every shared adapter boundary - #132

Status

Ready for review. This PR supersedes the intent of #130 while fixing the enforcement, provenance, prefix-validation, and test-coverage defects identified in review. All six repository CI jobs pass on the exact head.

Root cause

PR #130 placed the assertion only in run_scientific_single. The isolated Level Zero runner, Experiment 2, and direct adapter callers could bypass the check while still recording a requested pin in their manifests. Import-time provenance in wwgpt.ww could also become stale in notebooks, and the bidirectional prefix comparison accepted malformed or dangerously short values.

What changed

• Adds optional WWPGD_COMMIT_PIN runtime verification at both shared adapter boundaries:
  • before constructing the installed WW-PGD configuration;
  • before invoking the installed projector.
• Covers the main scientific runner, isolated Level Zero, Experiment 2, and direct shared-adapter callers without adding runner-specific assertions.
• Requires a 12–64 character hexadecimal SHA prefix.
• Uses one-directional matching only: resolved_commit.startswith(requested_pin).
• Rejects missing or non-hexadecimal PEP 610 commit metadata.
• Keeps the installation specification floating by default.

Truthful provenance

Manifests now distinguish runtime verification from installation pinning:

• wwpgd_resolved_commit
• wwpgd_commit_pin_requested
• wwpgd_commit_pin_verified
• wwpgd_commit_pin_status
• wwpgd_dependency_pinned = false

The provenance object is live with respect to the environment. A notebook that sets or clears WWPGD_COMMIT_PIN after importing wwgpt.ww records and enforces the current value rather than stale import-time state.

Compatibility

When WWPGD_COMMIT_PIN is unset or empty, behavior remains unchanged. This PR changes no optimizer mathematics, spectral target, dose, trust region, model weight, or default training behavior.

Validation

Deterministic tests cover:

• floating/unset behavior;
• full-SHA and valid prefix matches;
• uppercase normalization;
• too-short, nonhexadecimal, whitespace-containing, and overlong values;
• mismatch and reverse-prefix rejection;
• missing and malformed PEP 610 commit metadata;
• notebook/import-time environment changes;
• truthful manifest fields;
• enforcement at configuration and candidate boundaries;
• structural coverage of the root, isolated Level Zero, and Experiment 2 runners.

All six repository CI jobs pass on the exact head:

• complete portable test suite;
• quality, compilation, Ruff, and no-hard-coded-pin guard;
• Level 0–2 local runtime acceptance;
• macOS Python 3.10 / NumPy 1.x release acceptance;
• resolved pilot manifests;
• schema-v3 Papermill notebooks.

No scientific efficacy claim is made.